SOTU

The examples annotation format currently has three issues:

1. It doesn't differentiate between two separate examples and one example with multiple lines.
2. It's a bit annoying to escape characters (quotes, tabs, etc.) and these don't always display as expected in the html.
3. There are some inconsistencies in their formatting.

For example, around 40% of the multi-line examples are currently indented.

The rest are not.

I, personally, dislike this practice because it's not really in line with the code style and it's likely to be erased by auto-reformatting. That said, I understand why it's currently done for clarity.

The New Proposal

1. Each example gets its own annotation.
2. Each example is contained in one string. Multi-line examples can use Java 17's multi-line strings.
3. Formatting characters (quotes, whitespace, etc.) do not need to be escaped in this mode.
4. Possibly, include a flag for whether an example is just lines of code, or of an entire structure at the file root. Docs sites may want to display these differently in some way. (non-essential)

Side-by-Side

The current format:

The new (proposed) format: